/*
 *  Copyright (C) 2010 Glauco
 *
 *  This program is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

package org.balisunrise.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Esta anotação é utilizada em métodos que serão uma ação de uma busca ou
 * de um editor ou de uma própria transação.<br>
 * As ações são representadas, geralmente, por um botão na tela e disparada ao
 * usuário do sistema preciona-lo.<br>
 * No caso das classes em que este método pertense for um <code>ActionMap</code>
 * será possível interagir com os dados da busca, editor ou transação.
 *
 * @see org.balisunrise.common.ActionMap
 * @author glauco
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface VisualAction {

    /**
     * Representa os nomes para construção da ação.
     * Não informando os valores será atribuido a todos.
     * @return Retorna um array de nomes para esta definição de uma ação.
     */
    public String[] alias() default {};

    /**
     * Alvo onde a ação visual estará contida.
     * Não informando os valores será atribuido a todos os locais.
     * Os locais podem ser as entidades visuais Transaction, Editor e Seach,
     * além dos campos de entidades.
     * 
     * @return Array de tipos de VisualActionTarget validos para o ação.
     */
    public VisualActionTarget[] target() default {};

    /**
     * Propriedades que possão ser utilizadas para definir o alvo da ação
     * visual. Quando uma Ação tiver como Target um campo de entidade, deve
     * ser definido aqui o nome do campo.
     *
     * @return Array de propriedades.
     */
    public String[] properties() default {};

    /**
     * Indece da ação.
     * @return
     */
    public int index();

    /**
     * Icone da ação.<br>
     * Utilize um caminho completo para um arquivo, ou um caminho dentro do
     * projeto, ou ainda um dos nomes dos icones padrão do projeto.
     *
     * @see org.balisunrise.common.BaliIcons
     * @return
     */
    public String icon();

    /**
     * Texto para identificação da ação.
     * @return
     */
    public String text();

    /**
     * Texto de explicação da ação.
     * @return
     */
    public String toolTipText();

    /**
     * Determina se a representação visual da ação será focusable.
     * @return
     */
    public boolean focusable() default true;
}
